% arara: pdflatex: { files: [latexindent]}
\section{Fine tuning}\label{sec:finetuning}
 \texttt{latexindent.pl} operates by looking for the code blocks detailed in
 \vref{tab:code-blocks}.
 \announce{2019-07-13}{details of fine tuning of code blocks} The fine tuning of the
 details of such code blocks is controlled by the \texttt{fineTuning} field, detailed in
 \cref{lst:fineTuning}.

 This field is for those that would like to peek under the bonnet/hood and make some fine
 tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning}
 \index{regular expressions!fine tuning} \index{regular expressions!environments}
 \index{regular expressions!ifElseFi} \index{regular expressions!commands} \index{regular
 expressions!keyEqualsValuesBracesBrackets} \index{regular
 expressions!NamedGroupingBracesBrackets} \index{regular
 expressions!UnNamedGroupingBracesBrackets} \index{regular expressions!arguments}
 \index{regular expressions!modifyLineBreaks} \index{regular expressions!lowercase alph
 a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric
 0-9} \index{regular expressions!at least one +} \index{regular expressions!horizontal
 space \textbackslash{h}}

 \begin{warning}
  Making changes to the fine tuning may have significant consequences for your
  indentation scheme, proceed with caution!
 \end{warning}

 \begin{widepage}
  \cmhlistingsfromfile[style=fineTuning]{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,enhanced jigsaw,breakable,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning}
 \end{widepage}

 The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This
 manual is not intended to be a tutorial on regular expressions; you might like to read,
 for example, \cite{masteringregexp} for a detailed covering of the topic.

 We make the following comments with reference to \cref{lst:fineTuning}:
 \begin{enumerate}
  \item the \texttt{environments:name} field details that the \emph{name} of an
        environment can contain:
        \begin{enumerate}
         \item \texttt{a-z} lower case letters
         \item \texttt{A-Z} upper case letters
         \item \texttt{@} the \texttt{@} 'letter'
         \item \lstinline!\*! stars
         \item \texttt{0-9} numbers
         \item \lstinline!_! underscores
         \item \lstinline!\! backslashes
        \end{enumerate}
        \index{regular expressions!at least one +}
        The \texttt{+} at the end means \emph{at least one} of the above characters.
  \item the \texttt{ifElseFi:name} field:
        \begin{enumerate}
         \item \lstinline^@?^ means that it \emph{can possibly} begin with
               \lstinline^@^
         \item followed by \texttt{if}
         \item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and
               \texttt{@}
         \item the \texttt{?} the end means \emph{non-greedy}, which means `stop the
               match as soon as possible'
        \end{enumerate}
  \item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax:
        \begin{enumerate}
         \item \lstinline!|! means `or'
         \item \lstinline^(?:(?<!\\)\{)^ the \lstinline^(?:...)^ uses a \emph{non-capturing} group -- you don't necessarily need to worry about what this
               means, but just know that for the \texttt{fineTuning} feature you should only ever use
               \emph{non}-capturing groups, and \emph{not} capturing groups, which are simply
               \lstinline!(...)!
         \item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not} be immediately preceded by a \lstinline!\!
        \end{enumerate}
  \item in the \texttt{arguments:before} field
        \begin{enumerate}
         \item \lstinline^\d\h*^ means a digit (i.e. a number), followed by 0 or more horizontal spaces
         \item \lstinline^;?,?^ means \emph{possibly} a semi-colon, and possibly a comma
         \item \lstinline^\<.*?\>^ is designed for 'beamer'-type commands; the
               \lstinline^.*?^ means anything in between \lstinline^<...>^
        \end{enumerate}
  \item the \texttt{modifyLineBreaks} field refers to fine tuning settings detailed in
        \vref{sec:modifylinebreaks}. In particular:
        \begin{enumerate}
         \item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in
               \vref{sec:onesentenceperline}
         \item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and
               \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double backslashes, see
               \vref{subsec:dbs}
         \item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and
               \texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and
               mandatory arguments; see \vref{tab:poly-switch-mapping}
        \end{enumerate}
 \end{enumerate}

 It is not obvious from \cref{lst:fineTuning}, but each of the \texttt{follow},
 \texttt{before} and \texttt{between} fields allow trailing comments, line breaks, and
 horizontal spaces between each character.

 \index{warning!capture groups}
 \begin{warning}
  For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing
  groups, such as \lstinline!(?:...)! and \emph{not} capturing groups, which are
  \lstinline!(...)!
 \end{warning}

 \begin{example}
 As a demonstration, consider the file given in \cref{lst:finetuning1}, together with its
 default output using the command

 \begin{commandshell}
latexindent.pl finetuning1.tex 
\end{commandshell}

 is given in \cref{lst:finetuning1-default}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth]
  \cmhlistingsfromfile{demonstrations/finetuning1.tex}{\texttt{finetuning1.tex}}{lst:finetuning1}
  \cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default}
 \end{cmhtcbraster}

 It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not
 worked as expected. We can \emph{fine tune} the indentation scheme by employing the
 settings given in \cref{lst:fine-tuning1} and running the command \index{switches!-l
 demonstration}

 \begin{commandshell}
latexindent.pl finetuning1.tex -l=fine-tuning1.yaml
\end{commandshell}

 and the associated (desired) output is given in \cref{lst:finetuning1-mod1}.
 \index{regular expressions!at least one +}

 \begin{cmhtcbraster}[raster column skip=.01\linewidth]
  \cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1}
  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning1.yaml}[yaml-TCB]{\texttt{finetuning1.yaml}}{lst:fine-tuning1}
 \end{cmhtcbraster}
 \end{example}

 \begin{example}
 Let's have another demonstration; consider the file given in \cref{lst:finetuning2},
 together with its default output using the command

 \begin{commandshell}
latexindent.pl finetuning2.tex 
\end{commandshell}

 is given in \cref{lst:finetuning2-default}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth,
   raster left skip=-3.75cm,
   raster right skip=0cm,]
  \cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2}
  \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default}
 \end{cmhtcbraster}

 It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not
 worked as expected. We can \emph{fine tune} the indentation scheme by employing the
 settings given in \cref{lst:fine-tuning2} and running the command \index{switches!-l
 demonstration}

 \begin{commandshell}
latexindent.pl finetuning2.tex -l=fine-tuning2.yaml
\end{commandshell}

 and the associated (desired) output is given in \cref{lst:finetuning2-mod1}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth,
   raster left skip=-3.75cm,
   raster right skip=0cm,]
  \cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1}
  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2}
 \end{cmhtcbraster}

 In particular, note that the settings in \cref{lst:fine-tuning2} specify that
 \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can
 follow \texttt{"} and that we allow \lstinline!---! between arguments.
 \end{example}

 \begin{example}
 You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to
 use quotes appropriately. For example, starting with the code in \cref{lst:finetuning3}
 and running the following command

 \begin{commandshell}
latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?<!(?:(?:e\.g)|(?:i\.e)|(?:etc))))\.(?!(?:[a-z]|[A-Z]|\-|~|\,|[0-9]))"' issue-243.tex -o=+-mod1
\end{commandshell}

 gives the output shown in \cref{lst:finetuning3-mod1}.

 \cmhlistingsfromfile{demonstrations/finetuning3.tex}{\texttt{finetuning3.tex}}{lst:finetuning3}
 \cmhlistingsfromfile{demonstrations/finetuning3-mod1.tex}{\texttt{finetuning3.tex} using -y switch}{lst:finetuning3-mod1}
 \end{example}

 \begin{example}
 We can tweak the \texttt{fineTuning} for how trailing comments are classified. For
 motivation, let's consider the code given in \cref{lst:finetuning4}

 \cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4}

 We will compare the settings given in \cref{lst:href1,lst:href2}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth,
   raster left skip=0cm,
   raster right skip=-0.5cm,]
  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href1.yaml}[MLB-TCB]{\texttt{href1.yaml}}{lst:href1}
  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href2.yaml}[MLB-TCB]{\texttt{href2.yaml}}{lst:href2}
 \end{cmhtcbraster}

 Upon running the following commands

 \begin{commandshell}
latexindent.pl -m finetuning4.tex -o=+-mod1 -l=href1
latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2
\end{commandshell}

 we receive the respective output in \cref{lst:finetuning4-mod1,lst:finetuning4-mod2}.

 \begin{widepage}
  \cmhlistingsfromfile{demonstrations/finetuning4-mod1.tex}{\texttt{finetuning4.tex} using \cref{lst:href1}}{lst:finetuning4-mod1}

  \cmhlistingsfromfile{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2}
 \end{widepage}

 We note that in:
 \begin{itemize}
  \item \cref{lst:finetuning4-mod1} the trailing comments are assumed to be everything following
        the first comment symbol, which has meant that everything following it has been moved to
        the end of the line; this is undesirable, clearly!
  \item \cref{lst:finetuning4-mod2} has fine-tuned the trailing comment matching, and says that
        \% cannot
        be immediately preceded by the words `Handbook', `for' or `Spoken', which means that
        none of the \% symbols have been treated as trailing comments, and the output is
        desirable.
 \end{itemize}
 \end{example}

 \begin{example}
 Another approach to this situation, which does not use \texttt{fineTuning}, is to use
 \texttt{noIndentBlock} which we discussed in \vref{lst:noIndentBlock}; using the
 settings in \cref{lst:href3} and running the command

 \begin{commandshell}
latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3
\end{commandshell}

 then we receive the same output given in \cref{lst:finetuning4-mod2}.

 \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3}

 With reference to the \texttt{body} field in \cref{lst:href3}, we note that the
 \texttt{body} field can be interpreted as: the fewest number of zero or more characters
 that are not right braces. This is an example of character class. \index{regular
 expressions!character class demonstration}
 \end{example}

 \begin{example}
 We can use the \texttt{fineTuning} field to assist in the formatting of bibliography
 files. \index{bibliography files} \index{regular expressions!delimiterRegEx}
 \index{regular expressions!capturing parenthesis} \index{regular expressions!ampersand
 alignment} \index{delimiters!delimiterRegEx}

 Starting with the file in \cref{lst:bib1} and running the command

 \begin{commandshell}
latexindent.pl bib1.tex -o=+-mod1 
   \end{commandshell}

 gives the output in \cref{lst:bib1-mod1}.

 \begin{widepage}
  \begin{cmhtcbraster}[raster column skip=.01\linewidth]
   \cmhlistingsfromfile{demonstrations/bib1.bib}{\texttt{bib1.bib}}{lst:bib1}
   \cmhlistingsfromfile{demonstrations/bib1-mod1.bib}{\texttt{bib1-mod1.bib}}{lst:bib1-mod1}
  \end{cmhtcbraster}
 \end{widepage}

 Let's assume that we would like to format the output so as to align the \texttt{=}
 symbols. Using the settings in \cref{lst:bibsettings1} and running the command

 \begin{commandshell}
latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2 
     \end{commandshell}

 gives the output in \cref{lst:bib1-mod2}.

 \begin{widepage}
  \begin{cmhtcbraster}[raster column skip=.1\linewidth]
   \cmhlistingsfromfile{demonstrations/bib1-mod2.bib}{\texttt{bib1.bib} using \cref{lst:bibsettings1}}{lst:bib1-mod2}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings1.yaml}[yaml-TCB]{\texttt{bibsettings1.yaml}}{lst:bibsettings1}
  \end{cmhtcbraster}
 \end{widepage}
 Some notes about \cref{lst:bibsettings1}:
 \begin{itemize}
  \item we have populated the \texttt{lookForAlignDelims} field with the \texttt{online}
        command, and have used the \texttt{delimiterRegEx}, discussed in
        \vref{sec:delimiter-reg-ex};
  \item we have tweaked the \texttt{keyEqualsValuesBracesBrackets} code block so that it
        will \emph{not} be found following a comma; this means that, in contrast to the
        default behaviour, the lines such as \lstinline!date={2013-05-23},! will
        \emph{not} be treated as key-equals-value braces;
  \item the adjustment to \texttt{keyEqualsValuesBracesBrackets} necessitates the
        associated change to the \texttt{UnNamedGroupingBracesBrackets} field so that
        they will be searched for following \texttt{=} symbols.
 \end{itemize}
 \end{example}

 \begin{example}
 We can build upon \cref{lst:bibsettings1} for slightly more complicated bibliography
 files.

 Starting with the file in \cref{lst:bib2} and running the command

 \begin{commandshell}
latexindent.pl bib2.bib -l bibsettings1.yaml -o=+-mod1 
   \end{commandshell}

 gives the output in \cref{lst:bib2-mod1}.

 \begin{widepage}
  \cmhlistingsfromfile{demonstrations/bib2.bib}{\texttt{bib2.bib}}{lst:bib2}
  \cmhlistingsfromfile{demonstrations/bib2-mod1.bib}{\texttt{bib2-mod1.bib}}{lst:bib2-mod1}
 \end{widepage}

 The output in \cref{lst:bib2-mod1} is not ideal, as the \texttt{=} symbol within the url
 field has been incorrectly used as an alignment delimiter.

 We address this by tweaking the \texttt{delimiterRegEx} field in
 \cref{lst:bibsettings2}.

 \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings2.yaml}[yaml-TCB]{\texttt{bibsettings2.yaml}}{lst:bibsettings2}

 Upon running the command

 \begin{commandshell}
latexindent.pl bib2.bib -l bibsettings1.yaml,bibsettings2.yaml -o=+-mod2 
         \end{commandshell}

 we receive the \emph{desired} output in \cref{lst:bib2-mod2}.

 \cmhlistingsfromfile{demonstrations/bib2-mod2.bib}{\texttt{bib2-mod2.bib}}{lst:bib2-mod2}

 With reference to \cref{lst:bibsettings2} we note that the \texttt{delimiterRegEx} has
 been adjusted so that \texttt{=} symbols are used as the delimiter, but only when they
 are \emph{not preceded} by either \texttt{v} or \texttt{spfreload}.
 \end{example}

 \begin{example}
 We can use the \texttt{fineTuning} settings to tweak how \texttt{latexindent.pl} finds
 trailing comments. \announce{2023-06-01}{fine tuning trailing comments demonstration}

 We begin with the file in \cref{lst:finetuning5}

 \cmhlistingsfromfile{demonstrations/finetuning5.tex}{\texttt{finetuning5.tex}}{lst:finetuning5}

 Using the settings in \cref{lst:fine-tuning3} and running the command

 \begin{commandshell}
latexindent.pl finetuning5.tex -l=fine-tuning3.yaml
\end{commandshell}

 gives the output in \cref{lst:finetuning5-mod1}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth]
  \cmhlistingsfromfile{demonstrations/finetuning5-mod1.tex}{\texttt{finetuning5-mod1.tex}}{lst:finetuning5-mod1}
  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning3.yaml}[yaml-TCB]{\texttt{finetuning3.yaml}}{lst:fine-tuning3}
 \end{cmhtcbraster}

 The settings in \cref{lst:fine-tuning3} detail that trailing comments can \emph{not} be
 followed by a single space, and then the text `end'. This means that the
 \texttt{specialBeginEnd} routine will be able to find the pattern \lstinline!% end! as
 the \texttt{end} part. The trailing comments \texttt{123} and \texttt{456} are still
 treated as trailing comments.
 \end{example}

 \begin{example}
 We can use the \texttt{fineTuning} settings to tweak how \texttt{latexindent.pl} finds
 environments.

 We begin with the file in \cref{lst:finetuning6}.\announce{2023-10-13}{fineTuning
 environments}

 \cmhlistingsfromfile{demonstrations/finetuning6.tex}{\texttt{finetuning6.tex}}{lst:finetuning6}

 Using the settings in \cref{lst:fine-tuning4} and running the command

 \begin{commandshell}
latexindent.pl finetuning6.tex -m -l=fine-tuning4.yaml
\end{commandshell}

 gives the output in \cref{lst:finetuning6-mod1}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth,
   raster left skip=-3.5cm,
   raster force size=false,
   raster column 1/.style={add to width=-.1\textwidth},
   raster column 2/.style={add to width=-.3\textwidth},
  ]
  \cmhlistingsfromfile{demonstrations/finetuning6-mod1.tex}{\texttt{finetuning6-mod1.tex}}{lst:finetuning6-mod1}
  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning4.yaml}[MLB-TCB]{\texttt{fine-tuning4.yaml}}{lst:fine-tuning4}
 \end{cmhtcbraster}

 By using the settings in \cref{lst:fine-tuning4} it means that the default poly-switch
 location of \texttt{BodyStartsOnOwnLine} for environments (denoted
 $\BodyStartsOnOwnLine$ in \cref{tab:poly-switch-mapping}) has been overwritten so that
 it is \emph{after} the \texttt{label} command.

 Referencing \cref{lst:fine-tuning4}, unless both \texttt{begin} and \texttt{end} are
 specified, then the default value of \texttt{name} will be used.
 \end{example}
